Stabilize Glaze architecture, runtime, security, packaging, and cross-platform APIs - #5

Summary

This PR has grown from an architecture/documentation cleanup into a broad pre-1.0 stabilization pass. The goal remains low-risk and mergeable: preserve the public facade, fix concrete cross-platform failures, harden capability boundaries, improve release engineering, and add regression coverage rather than redesigning Glaze into an Electron clone.

Glaze's positioning is now explicit: a Lisp-native framework for building modern desktop applications with Racket, using a web UI, a Racket runtime, system WebViews, and native OS capabilities.

Main changes

Architecture and public API

• rewrote English and Chinese READMEs around the current product model
• added docs/architecture.md, ROADMAP.md, SECURITY.md, and docs/releasing.md
• kept (require glaze) as the compatibility-preserving public facade
• documented Public / Internal / Platform-specific boundaries
• added facade and contract regression tests for WebView, tray/menu, sys, dialogs, API routes, updater, CLI behavior, and static serving

Runtime and security hardening

• strengthened local-server Host / Origin / capability-token protections
• hardened generated browser/SSE client behavior and one-time bootstrap handling
• fixed environment restoration compatibility with Racket 8.12
• made browser fallback failures explicit instead of leaving a headless server running
• normalized API route registration and fail-fast handler arity/parameter validation
• hardened system/tray/WebView facade argument contracts before values reach native FFI
• static assets are now streamed from disk with copy-port instead of loading the entire file into the Racket heap; a real 4 MiB WASM HTTP regression test locks down status, MIME type, length, and bytes

WebView and macOS behavior

• fixed packaged-entry execution so (module+ main ...) actually runs
• added dedicated macOS + Racket 9.3 final-launcher regression coverage for issue build-app: assembled .app launcher exits 0 without running the program (Racket 9.3 CS) #1
• preserved the shared macOS run-loop pump and multi-window lifecycle behavior
• added opt-in background activity support and public WKPreferences.inactiveSchedulingPolicy handling for monitoring-style apps without using private WebKit APIs

Native capability fixes

• fixed Windows folder picking to use the Shell folder API
• fixed Windows multi-file dialog UTF-16 multi-string parsing
• fixed a Windows save-dialog buffer-size mismatch that could expose an undersized native buffer
• hardened menu/tray/system API contracts
• made Windows autolaunch deletion distinguish real registry failures from an already-absent entry

Packaging and distribution

• fixed Linux AppImage environment restoration
• Windows installer probing now identifies the actual wix executable, checks wix --version, and only uses WiX major version 4; newer majors fall through to NSIS / archive fallback instead of being fed WiX 4 source accidentally
• verifies installer artifacts exist after the tool reports success
• Windows CI exercises NSIS; Linux CI intentionally exercises the portable .tar.gz fallback instead of downloading AppImageKit's mutable continuous binary
• verifies the macOS bundle signature in CI
• added a source-package job: raco pkg create --source, fresh archive install, (require glaze), and raco glaze help
• moved test-only RackUnit dependency to build dependencies and declared source distribution preference
• added a release checklist separating CI smoke artifacts from production-signed/notarized artifacts

CLI and update/license tooling

• CLI parsers now fail on unknown/missing arguments instead of silently accepting mistakes
• fixed license --machine-id parsing interaction with following options
• verify requires exactly one license file
• key generation avoids silently overwriting existing private keys, cleans partial output on failure, and applies 0600 private-key permissions on Linux/macOS
• update manifest reading now handles short network reads correctly, enforces the size cap, and validates version/URL/notes/SHA-256 schema

CI, supply chain, and repository hygiene

• CI token permissions are reduced to contents: read
• jobs have explicit timeouts and stale PR runs are cancelled
• GitHub Actions are pinned to exact reviewed commit SHAs and use Node 24-compatible releases (checkout v5.1.0, setup-racket v1.15, upload-artifact v7.0.1)
• added Dependabot for GitHub Actions, PR/bug templates, .editorconfig, .gitattributes, and safer ignore rules for generated installers and private signing material

Compatibility

No existing public binding was intentionally removed or renamed. Focused module imports remain available. Platform backends remain behind their dispatchers; the stabilization work avoids unnecessary directory moves or a large runtime rewrite.

Validation

At head a5e57a05658891f43b492ecc9d3ffcc6176aab31, GitHub Actions run #145 completed successfully after retrying one transient GitHub artifact-finalization ECONNRESET:

• Racket 8.12 public-entry compilation and 306 tests on Windows, macOS, and Ubuntu
• native WebView end-to-end tests on all three platforms
• sample app packaging / installer builds on all three platforms
• Windows NSIS installer generation and artifact upload
• macOS ad-hoc bundle signing + strict signature verification
• Linux portable installer fallback with an asserted non-empty .tar.gz
• macOS package regression on Racket 9.3 executing the final packaged launcher
• source-package archive creation, fresh install, public facade load, and CLI verification
• 4 MiB static-asset HTTP streaming regression

Issue #1 is closed with dedicated regression coverage. Issue #2 remains open intentionally: the public macOS anti-throttling mitigation is implemented, but the original fully-occluded-window timing scenario still needs a dedicated real-world reproduction test before declaring it resolved.

Remaining repository / release setup outside this PR

• GitHub Repository Rulesets are currently absent; branch-protection details could not be read with the installed GitHub App permissions. main should require PR review and the CI workflow as required checks in repository settings.
• Production releases still require real publisher credentials and clean-machine smoke tests for macOS notarization / Developer ID signing and Windows code signing.